⚠️ Show-case only! Needs some adjustments before actual merge

This is a PoC to leverage a simple custom code generator for gql queries to python

Background

Design Doc

GraphQL data is currently used in un-typed nested dictionaries. Adding type safety will increase maintainability of the code base. Non-compliant schema changes (some integrations are using a schema that you might not be aware of) are more likely to raise errors during development.

We use a similar approach for our go integrations.

Reviewer Notes

Query examples and their corresponding generated code can be found in reconcile/gql_queries.

The module code_generator is a proof the concept, i.e., it is not feature complete with everything GQL has to offer. However, it covers our most common use-cases, like standard queries and inline fragments. If we decide to go forward with a custom code generator approach, then it requires a bit more work to adhere to best practices.

The module reconcile.gql_queries contains the query definitions .gql files and the corresponding generated .py files. Those .py files are then consumed in reconcile.

Implementation Details

A query is defined in a .gql file. The content of a .gql file is a valid query that could be used with curl against a GQL backend.
All .gql files are placed under the gql_queries directory.

Running make generate-queries will:

1. Run an introspection query against a GQL backend, i.e., fetch the schema
2. Read all .gql files under reconcile/gql_queries
3. For each .gql file, generate the AST and match it with the types from the schema, i.e., generate a typed AST
4. Generate a corresponding .py file for each .gql file and place it in the same (sub)directory

In the end the reconcile/gql_queries directory could look like this:

reconcile/gql_queries/
├── __init__.py
└── saas_files
    ├── __init__.py
    ├── saas_files_full.gql
    ├── saas_files_full.py
    ├── saas_files_small_with_provider.gql
    └── saas_files_small_with_provider.py

The generated .py files can be consumed like:

from gql_queries.saas_files import saas_files_full


with open("reconcile/gql_queries/saas_files/saas_files_full.gql", "r") as f:
    query = f.read()

data: dict[Any, Any] = gqlapi.query(query)
apps: list[AppV1] = saas_files_full.MyQuery(**data).apps_v1 or []

Other

There is a parallel PoC open for a 3rd party code generator #2367